package com.starview.platform.resource;

import java.io.InputStream;
import java.io.Reader;

import com.starview.platform.data.value.ResourceURI;

/**
 * The Transducer interface is used when accessing and maintaining resources
 * 
 * @author fgm
 * 
 */
public interface Transducer
{
  /**
   * Access the contents of a resource as a reader
   * 
   * @param uri
   * @return the string contents of the resource -- if possible.
   * @throws ResourceException
   *           if the resource does not exist or cannot be accessed
   */
  Reader getReader(ResourceURI uri) throws ResourceException;

  /**
   * Access the resource as a stream of bytes
   * 
   * @param uri
   * @return
   * @throws ResourceException
   */
  InputStream getInputStream(ResourceURI uri) throws ResourceException;

  /**
   * PUT the identified resource at the location indicated by the uri.
   * 
   * @param uri
   * @param resource
   * @throws ResourceException
   */
  void putResource(ResourceURI uri, Object resource) throws ResourceException;

  /**
   * Try to determine if the uri identifies an accessable resource
   * 
   * @param uri
   *          the uri to verify
   * 
   * @return true if can read, false if you cannot
   * @throws ResourceException
   *           if the uri is not well formed
   */
  boolean exists(ResourceURI uri) throws ResourceException;
}
